--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Commit 38b783aa1a376fd038075798f38568817d2313da
Parents : f9c8c46
Author : Ivan <ivan@quad4.io>
Signature : Invalid signer <e46112d44649266d71fe2193e00a4710>, author is <ivan@quad4.io>
Date : 2026-07-04T16:10:30-05:00
feat(documentation): update README with troubleshooting section for database issues, including recovery options and data storage locations
Changes
Diff
diff --git a/README.md b/README.md
index 630a8668..4820400b 100644
--- a/README.md
+++ b/README.md
@@ -435,6 +435,56 @@ Current version in this repo is `4.7.2`.
- **`meshchatx.__version__`** is read from **`meshchatx/src/version.py`** without importing **`meshchatx.src`**, so a plain `import meshchatx` stays lightweight.
- **Changelog** entries stay manual when you cut a release.
+## Troubleshooting: database corruption and full data reset
+
+If MeshChatX fails to start with errors such as `database disk image is malformed`, `DatabaseError`, or corrupted ratchet data, the desktop crash screen now offers recovery actions:
+
+- **Restore latest backup** from `database-backups/` or `snapshots/` inside your MeshChatX storage folder
+- **Choose backup file** to restore a `.zip` you saved elsewhere
+- **Try auto-repair** to relaunch with `--auto-recover` (SQLite checkpoint / integrity pass)
+- **Emergency mode** to open the app without the database so you can export data from About when possible
+- **Copy reset instructions** with the exact folders to delete for a clean reinstall
+
+### Where MeshChatX stores data
+
+| Platform | MeshChatX storage | Reticulum network stack |
+| --- | --- | --- |
+| Linux / macOS | `~/.reticulum-meshchatx/` | `~/.reticulum/` |
+| Windows | `%USERPROFILE%\.reticulum-meshchatx\` | `%USERPROFILE%\.reticulum\` |
+| Windows portable | `<MeshChatX.exe folder>\.reticulum-meshchatx\` | `<MeshChatX.exe folder>\.reticulum\` |
+
+Legacy Reticulum MeshChat data may still exist at `~/.reticulum-meshchat/` (or the Windows equivalent).
+
+Automatic database backups are written to:
+
+`database-backups/` inside the MeshChatX storage folder when the app has run successfully before.
+
+### Complete removal (start fresh)
+
+Quit MeshChatX completely. On Windows, also end `ReticulumMeshChatX.exe` in Task Manager if it is still running. Then delete the MeshChatX storage folder and the Reticulum config folder for your install type (see table above). This removes your local identity, messages, contacts, path cache, and ratchet state. The next launch creates a new identity unless you restore from a backup first.
+
+**Linux / macOS example:**
+
+```bash
+rm -rf ~/.reticulum-meshchatx ~/.reticulum ~/.reticulum-meshchat
+```
+
+**Windows (PowerShell) example:**
+
+```powershell
+Remove-Item -Recurse -Force "$env:USERPROFILE\.reticulum-meshchatx", "$env:USERPROFILE\.reticulum", "$env:USERPROFILE\.reticulum-meshchat" -ErrorAction SilentlyContinue
+```
+
+Custom installs: if you pass `--storage-dir` or `--reticulum-config-dir`, remove those directories instead of the defaults.
+
+### Command-line restore (advanced)
+
+When the backend can start briefly or you run from source:
+
+```bash
+meshchatx --storage-dir /path/to/storage --restore-db /path/to/backup.zip
+```
+
## Security
Security and integrity details:
diff --git a/android/README.md b/android/README.md
index 69dcb2fc..eb6cfbe5 100644
--- a/android/README.md
+++ b/android/README.md
@@ -11,7 +11,7 @@ Native APK with embedded Python (`meshchatx/`) and a WebView UI.
## Lint and static analysis
- **Android Lint** (Java, Kotlin, manifests, resources): from `android/`, run `./gradlew --no-daemon :app:lintDebug`. HTML report: `app/build/reports/lint-results-debug.html`. CI runs this in the Android workflow when tests run.
-- **SAST (GitHub CodeQL)**: the repository workflow includes a `java-kotlin` matrix entry (see `.github/workflows/codeql.yml`) for GitHub’s security analysis on default branches and PRs.
+- **SAST (GitHub CodeQL)**: the repository workflow includes a `java-kotlin` matrix entry (see `.github/workflows/security.yml`) for GitHub’s security analysis on default branches and PRs.
## Launcher shortcuts, language
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────